Skip to content

docs(automation): add structured Automation, Skills, and nix-claude-code surface#30

Open
JacobPEvans wants to merge 5 commits into
mainfrom
docs/automation-surface
Open

docs(automation): add structured Automation, Skills, and nix-claude-code surface#30
JacobPEvans wants to merge 5 commits into
mainfrom
docs/automation-surface

Conversation

@JacobPEvans
Copy link
Copy Markdown
Owner

@JacobPEvans JacobPEvans commented May 24, 2026

Summary

  • Add the Automation nav group with subdirectories for cloud-pipelines/ and scheduled-routines/ instead of a flat list, so the surface can absorb future growth without becoming a wall of siblings.
  • Add ai-development/skills/ for local Claude Code slash-commands (/ship, /resolve-codeql). These were briefly under automation/ before review — they are agent tooling, not pipeline plumbing, so they live in AI Development now.
  • Add nix/nix-claude-code documenting the declarative Claude Code home-manager modules in dryvist/nix-claude-code, with explicit cross-links to the rest of the Nix stack (nix-darwin, nix-home, nix-ai, nix-devenv).
  • Codify the cost-and-tier reporting policy in security/scrubbed-values.mdx: no specific subscription-tier names, no $N/day, costs are monthly with per-instance × instances/month math.

What's in the new nav

Group New pages
Automation overview, issue-to-pr-pipeline, cloud-pipelines/{overview, ai-workflows}, scheduled-routines/{overview, claude-code-routines}
AI Development skills/{overview, ship-and-finalize, codeql-resolution}
Nix Ecosystem nix-claude-code

What's deleted

  • automation/shape-issues.mdx — the /shape-issues skill is not actually in use; Claude plan mode covers the same workflow.

Content scrubs

  • automation/cloud-pipelines/ai-workflows.mdx: Claude Max plan's $200/month automation credits → vague included monthly automation credits on the Claude subscription that backs these workflows.
  • Two stale agentsmd/rules/*.md links (broken when docs: migrate cross-repo standards from ai-assistant-instructions #32 migrated those rules) repointed at /infrastructure/cicd/policy and /infrastructure/cicd/git-signing.

Verification

  • jq empty docs.json
  • Single canonical Mermaid theme directive across the site ✓
  • 27 internal links audited; all resolve ✓
  • No stale /automation/<old-name> references ✓
  • No $200, Max plan, Pro plan, $N/day leaks (the policy text in scrubbed-values.mdx itself is the only intentional match) ✓
  • Final commit signed with the local GPG key ✓
  • All required CI checks SUCCESS, mergeStateStatus: CLEAN
  • CodeQL alerts: 0 ✓

Test plan

  • mint dev — confirm the Automation sidebar shows the two new sub-groups (Cloud pipelines, Scheduled routines), AI Development shows the new Skills sub-group, and Nix Ecosystem lists nix-claude-code between nix-devenv and package-placement.
  • Click each card on /automation/overview — three pillars now (Cloud pipelines, Scheduled routines, Skills).
  • Spot-check that /automation/cloud-pipelines/ai-workflows no longer contains the Claude Max plan / $200/month wording.
  • mint broken-links.

Refs: #32

@mintlify
Copy link
Copy Markdown

mintlify Bot commented May 24, 2026

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
jacobpevans 🟢 Ready View Preview May 24, 2026, 4:31 PM

Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a comprehensive "Automation" section to the documentation, detailing the mechanics of the issue-to-mergeable PR pipeline. It adds several new pages covering ai-workflows, claude-code-routines, codeql-resolution, shape-issues, and the /ship and /finalize-pr skills, while updating navigation and cross-references across existing files. Feedback from the review highlights a timezone inconsistency in the routine schedule and a count mismatch in the automation overview heading.

Comment thread automation/claude-code-routines.mdx Outdated
Comment thread automation/overview.mdx Outdated
JacobPEvans added a commit that referenced this pull request May 24, 2026
…g parts

Addresses gemini-code-assist review on PR #30:

- claude-code-routines.mdx: README in source repo lists all routines in
  CT, not UTC. Updated table header to "Schedule (CT)" and corrected
  every row to match the source-of-truth times from the README.
- overview.mdx: heading said "seven moving parts" but the CardGroup
  has six cards. Changed to "six moving parts".

Assisted-by: Claude <noreply@anthropic.com>
Adds a new top-level Automation nav group with seven pages covering the
end-to-end issue->mergeable-PR pipeline that spans three repos:

- automation/overview — the three-layer pipeline (cloud GHA, cron
  routines, local /ship) with a canonical end-to-end diagram
- automation/issue-to-pr-pipeline — the eight-step cloud flow on this
  repo, with which trigger fires which caller and what each does
- automation/ai-workflows — catalog of the 16 reusable workflows in
  JacobPEvans/ai-workflows: event-triggered, scheduled, and what's
  deprecated or disabled
- automation/claude-code-routines — the six cron-scheduled cloud
  routines: morning briefing, sentinel, custodian, issue solver, daily
  polish, weekly scorecard; the deploy-routines GHA workaround
- automation/ship-and-finalize — /ship + /finalize-pr lifecycle with
  the canonical five-phase diagram and the known reliability gaps
  being closed in a follow-up against claude-code-plugins
- automation/codeql-resolution — why CodeQL is fixed separately from
  CI checks, and how /resolve-codeql plugs into /finalize-pr Phase 2
- automation/shape-issues — the /shape-issues local skill and how it
  feeds well-scoped issues into the resolver pipeline

Cross-links from existing pages:
- architecture/ai-pipeline.mdx -> /automation/overview (mechanics)
- tools/automation.mdx -> /automation/overview + /automation/ship-and-finalize
- ai-development/claude-code-plugins.mdx -> /automation/ship-and-finalize
  + replaces direct GitHub links with /automation/* internal links for
  claude-code-routines and ai-workflows

All new diagrams use the canonical hand-drawn Reef Green theme directive
byte-for-byte; grep validates one unique directive across the site.
Word counts within tier caps (tier 1 <=450, tier 2 <=900). All internal
links validated by mint broken-links.

Assisted-by: Claude <noreply@anthropic.com>
…g parts

Addresses gemini-code-assist review on PR #30:

- claude-code-routines.mdx: README in source repo lists all routines in
  CT, not UTC. Updated table header to "Schedule (CT)" and corrected
  every row to match the source-of-truth times from the README.
- overview.mdx: heading said "seven moving parts" but the CardGroup
  has six cards. Changed to "six moving parts".

Assisted-by: Claude <noreply@anthropic.com>
…I key

ai-workflows now authenticates directly against the Anthropic API
using ANTHROPIC_API_KEY, drawing from the Claude Max plan's
$200/month automation credits. OpenRouter remains supported as a
fallback provider but is no longer the default.

- ai-workflows.mdx: Authentication section rewritten; secret list
  swapped (ANTHROPIC_API_KEY replaces OPENROUTER_API_KEY +
  OPENROUTER_BASE_URL); fallback mention kept for completeness;
  "Where to go next" cards updated.
- issue-to-pr-pipeline.mdx: secrets table updated; auth card
  description matches the new default.

Assisted-by: Claude <noreply@anthropic.com>
… add nix-claude-code

Restructure the Automation group for future growth:

- automation/cloud-pipelines/  (NEW subdir) — ai-workflows lives here now
- automation/scheduled-routines/  (NEW subdir) — claude-code-routines lives here
- ai-development/skills/  (NEW subdir) — ship-and-finalize, codeql-resolution moved
  out of automation/ since they are local Claude skills, not pipeline plumbing
- nix/nix-claude-code  (NEW page) — declarative Claude Code via home-manager,
  the missing piece between the binary (nix-ai) and the install (this)
- automation/shape-issues  DELETED — /shape-issues is not actually used; Claude
  plan mode covers the same workflow

Each new subdirectory carries its own overview.mdx as a landing page. The
top-level automation/overview now points at three pillars (Cloud pipelines,
Scheduled routines, Skills) instead of a flat seven-card grid.

Also scrub the Claude Max plan / $200/month pricing line in ai-workflows.mdx
(replaced with "included monthly automation credits on the Claude subscription
that backs these workflows"), and codify the cost-and-tier reporting rule in
security/scrubbed-values.mdx:
- Never name a specific AI subscription tier in committed content
- Cost figures are monthly with the per-instance × instances/month math visible
- Schedules and rate limits are not costs and stay as-is

Also fix two stale agentsmd/rules/* references that were broken by the prior
rules-migration PR:
- automation/cloud-pipelines/ai-workflows.mdx: ci-cd-policy.md link now points
  at /infrastructure/cicd/policy
- automation/issue-to-pr-pipeline.mdx: git-signing.md link now points at
  /infrastructure/cicd/git-signing

27 internal links audited; all resolve. JSON valid. Mermaid theme directive
remains the single canonical form across the site.

Assisted-by: Claude <noreply@anthropic.com>
@JacobPEvans JacobPEvans changed the title docs: add Automation section covering ai-workflows, routines, /ship docs(automation): add structured Automation, Skills, and nix-claude-code surface May 25, 2026
The section listed marketing tiers (Claude Max, ChatGPT Pro, Copilot
Business) by name as a forbidden list, which made the public docs site
the public memorial of a behavioral rule that belongs in agent context,
not on a docs page.

The underlying behavior — no specific pricing or tier names in committed
content — stays as agent guidance.

Assisted-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant